Skip to main content

Ficha técnica

Escopos necessários​

O token para consumir a API de Vendas do BTG Pay deve ser gerado usando o Authorization Code.

O escopo openid é obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário incluir o seguinte escopo:

EscopoDescrição
brn:btg:empresas:acquirer:dashboard.sales.readonlyPermite a consulta de vendas.

Vendas — Visão Geral da API

A API de Venda do BTG Pay permite que aplicativos parceiros consultem, em nome do cliente, o histórico de vendas. Esta documentação apresenta os principais fluxos disponíveis e como utilizá-los para montar o dashboard do parceiro.

Todos os recursos são somente leitura e recebem no path o companyId, que é o CNPJ da empresa cujos dados serão consultados. Os fluxos se organizam em torno do conceito central:

  • Venda — a transação capturada, com seu valor bruto, valor líquido, método de pagamento e o canal onde foi realizada.

Os valores monetários são representados por objetos com os campos currency (moeda, ex.: BRL) e value (valor decimal como string, com duas casas decimais — ex.: "150.75"). Os enums de modalidade, canal e bandeira são retornados em minúsculas (credit_card, pos, visa).

Fluxo de Vendas​

O fluxo de vendas dá visibilidade sobre as transações do cliente. A partir dele, o parceiro monta a lista de vendas do dashboard e aprofunda em cada transação individual.

Listagem de Vendas​

O ponto de entrada do fluxo é a listagem de vendas. Ela retorna o histórico de transações capturadas, permitindo que sua aplicação exiba, para cada venda, a modalidade de pagamento, o canal, os valores bruto e líquido e as datas do ciclo de vida da transação.

A listagem aceita filtros por intervalo de datas (startDate e endDate, no formato yyyy-MM-dd), por bandeira do cartão (cardBrand) e por modalidade de venda (saleType — credit_card, debit_card ou pix). A resposta é paginada por cursor: cada página traz o cursor da próxima em _links.next, que deve ser repassado no parâmetro cursor para avançar. Quando next vem null, não há mais páginas.

Requisição — GET /{companyId}/acquirer/sales?startDate=2026-07-01&endDate=2026-07-31&pageSize=20

Resposta — 200 OK

{
  "_links": {
    "prev": null,
    "next": {
      "href": "/30306294000145/acquirer/sales?cursor=eyJpZCI6Ii4uLiJ9",
      "method": "GET"
    }
  },
  "data": [
    {
      "id": "8f3a1c2e-0b4d-4e2a-9c1f-7a6b5d4e3c2b",
      "type": "credit_card",
      "channel": "pos",
      "grossAmount": { "currency": "BRL", "value": "150.75" },
      "netAmount": { "currency": "BRL", "value": "146.20" },
      "paymentMethod": {
        "cardBrand": "visa",
        "cardNumber": "**** **** **** 1234",
        "installments": 3
      },
      "saleDate": "2026-07-10T14:32:05Z",
      "capturedAt": "2026-07-10T14:32:07Z",
      "authorizedAt": "2026-07-10T14:32:06Z"
    }
  ]
}

Detalhes da Venda​

Para cada venda listada, é possível acessar sua visão detalhada. Esta consulta retorna os mesmos dados da listagem para a venda específica, sendo usada para exibir a tela de detalhe de uma transação no dashboard do parceiro.

O identificador da venda (saleId) é o mesmo campo id retornado na listagem. Caso a venda não exista, a API retorna 404 Not Found.

Requisição — GET /{companyId}/acquirer/sales/{saleId}

Resposta — 200 OK

{
  "id": "8f3a1c2e-0b4d-4e2a-9c1f-7a6b5d4e3c2b",
  "type": "credit_card",
  "channel": "pos",
  "grossAmount": { "currency": "BRL", "value": "150.75" },
  "netAmount": { "currency": "BRL", "value": "146.20" },
  "paymentMethod": {
    "cardBrand": "visa",
    "cardNumber": "**** **** **** 1234",
    "installments": 3
  },
  "saleDate": "2026-07-10T14:32:05Z",
  "capturedAt": "2026-07-10T14:32:07Z",
  "authorizedAt": "2026-07-10T14:32:06Z"
}

O campo channel indica onde a venda foi realizada: web (e-commerce), pos (maquininha) ou tef (transferência eletrônica de fundos). O campo type indica a modalidade de pagamento: credit_card, debit_card ou pix.

Paginação​

As listagens de vendas e de unidades recebíveis usam paginação por cursor. Cada resposta traz um objeto _links com os cursores prev e next. Para buscar a próxima página, repita a requisição informando, no parâmetro cursor, o valor retornado em _links.next. O cursor é opaco e deve ser tratado como um identificador único da posição do último item visto na página atual. O tamanho da página é controlado pelo parâmetro pageSize.